.\" Copyright (C) 2019 VirtualSquare. Project Leader: Renzo Davoli
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License,
.\" as published by the Free Software Foundation, either version 2
.\" of the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, write to the Free
.\" Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston,
.\" MA 02110-1301 USA.
.\"
.\" Automatically generated by Pandoc 3.1.11
.\"
.TH "UMVU" "1" "January 2024" "VirtualSquare\-VUOS" "General Commands Manual"
.SH NAME
\f[CB]umvu\f[R] \[en] user\-mode implementation of VUOS
.SH SYNOPSIS
\f[CB]umvu\f[R] [\f[I]options\f[R] \&...]
\f[I]command\f[R] [\f[I]args\f[R]]
.SH DESCRIPTION
VUOS: view based operating system.
VUOS gives processes their own view of the system resources.
VUOS is a different perspective on namespaces, anykernels and related
concepts.
The main idea behind VUOS is that it is possible to give processes their
own \f[I]view\f[R] using partial virtual machines.
.PP
A partial virtual machine intercepts the system call requests and
operates like a filter: system call can be forwarded to the kernel of
the hosting system or processed by the partial virtual machine
hypervisor.
.PP
In this way processes can see a mix of resources provided by the kernel
(on which they have the same view of the other processes) and virtual
resource.
It is possible to mount filesystems, load networking stacks, change the
structure of the file system tree, create virtual devices, etc.
.PP
\f[CB]umvu\f[R] is a user mode implementation of VUOS concepts It is a
modular partial virtual machine.
Before loading any module, \f[CB]umvu\f[R] is completely transparent, a
process behaves inside \f[CB]umvu\f[R] as it would have behaved outside.
\f[I]vu_insmod\f[R](1) is the tool to load modules,
e.g.\ \f[I]vufuse\f[R] for file system virtualization, \f[I]vunet\f[R]
for networking, \f[I]vudev\f[R] for virtual devices, etc.
These are just some examples of modules provided by the VirtualSquare
team: modules are dynamic library based plugins so can be designed and
implemented independently and loaded/unloaded at run time.
.PP
\f[CB]umvu\f[R] (VUOS hypervisor) is just a user process so, while it
gives new perspective for processes, it does not widen the attack
surface of the kernel.
.SH OPTIONS
.TP
\f[CB]\-h\f[R], \f[CB]\-\-help\f[R]
Print a short help message and exit.
.TP
\f[CB]\-x\f[R], \f[CB]\-\-nonesting\f[R]
\f[CB]umvu\f[R] provides nested virtualization.
It means that the system call requests
of the modules can refer to virtual resource.
(for example it is possible to mount
a file system stored on a virtual device).
The \f[CB]\-x\f[R] or \f[CB]\-\-nonesting\f[R] option disables this
feature.
.TP
\f[CB]\-S\f[R], \f[CB]\-\-noseccomp\f[R]
\f[CB]umvu\f[R] uses a seccomp filter to speed\-up the virtualization.
The \f[CB]\-S\f[R] or \f[CB]\-\-noseccomp\f[R] option disables this
feature.
.TP
\f[CB]\-f\f[R] \f[I]file\f[R], \f[CB]\-\-rc\f[R] \f[I]file\f[R]
Execute commands from file instead of the system wide initialization
file
\f[I]/etc/vurc\f[R] and the standard personal initialization file
\f[I]\[ti]/.vurc\f[R]
.TP
\f[CB]\-N\f[R], \f[CB]\-\-norc\f[R]
Do not run the system wide initialization file
\f[I]/etc/vurc\f[R] and the standard personal initialization file
\f[I]\[ti]/.vurc\f[R]
.TP
\f[CB]\-V\f[R] \f[I]name\f[R], \f[CB]\-\-vu_name\f[R] \f[I]name\f[R]
set the name of the view.
This name can be read and set using \f[CB]vuname\f[R](1)
.TP
\f[CB]\-d\f[R] \f[I]debugtags\f[R], \f[CB]\-\-debugtags\f[R] \f[I]debugtags\f[R]
set the debug tags enabled from the beginning.
e.g.\ \f[CB]\-d s\f[R] enables
log messages of system call requests.
(see \f[CB]vudebug\f[R](1) for a detailed
description)
.TP
\f[CB]\-D\f[R] \f[I]colorspec\f[R], \f[CB]\-\-debugcols\f[R] \f[I]colorspec\f[R]
set color and font effects for log messages.
e.g.\ \f[CB]\-D p:r \-D c:g#\f[R]
means that path resolution messages will be displayed in red while
module choice log will be in reverse green.
Color definition can refer to
enable and disabled categories (the option defines the colors for
a successive activation).
(see \f[CB]vudebug\f[R](1) for a detailed
description)
.TP
\f[CB]\-l\f[R] \f[I]level\f[R], \f[CB]\-\-loglevel\f[R] \f[I]level\f[R]
set the debug level.
Only messages having level less or equal of
the parameter of this option will be displayed.
(0 = emergency, 1 = alert, 2 = critical, 3 = error, 4 = warning, 5 =
notice, 6 = info, 7 = debug).
The default level is 4.
.TP
\f[CB]\-s\f[R] \f[I]level\f[R], \f[CB]\-\-syslog\f[R] \f[I]level\f[R]
use \f[CB]syslog\f[R](2) for logging and log messages having level less
or equal of
the parameter of this option.
(0 = emergency, 1 = alert, 2 = critical, 3 = error, 4 = warning, 5 =
notice, 6 = info, 7 = debug).
This option is disabled by default.
.SH EXAMPLES
.SS mount a file system image
The following example mounts /tmp/linux.img on /mnt.
.PP
start the hypervisor, and run a bash \f[I]inside\f[R] the partial
virtual machine
.IP
.EX
$ umvu bash
.EE
.PP
This is the prompt of the partial virtualized shell, let us change it to
$$ to show the difference
.IP
.EX
$ PS1=\[aq]\[rs]$\[rs]$ \[aq]\[ga]
.EE
.PP
let us load vufuse: a user\-mode implementation of FUSE (source
compatible with FUSE modules)
.IP
.EX
$$ vu_insmod vufuse
.EE
.PP
nothing is currently mounted on /mnt
.IP
.EX
$$ ls /mnt
.EE
.PP
the following command mounts the filesystem image /tmp/linux.img
.IP
.EX
$$ vumount \-t vufuseext2 \-o ro /tmp/linux.img /mnt
.EE
.PP
now the image has been mounted:
.IP
.EX
$$ ls /mnt
bin  boot  dev  etc  lib  lost+found  mnt  proc  sbin  tmp  usr
$$ vuumount /mnt
$$ ls /mnt
$$ exit
.EE
.PP
We have left the partial virtual machine
.PP
Comments: user can \f[I]mount\f[R] any filesystem they like, on any
directory.
The linux kernel is not involved for all the system calls related to
files in the mounted filesystem.
The effects of this \f[I]mount\f[R] is just \f[I]perceived\f[R] by the
processes running in the partial virtual machine.
\f[CB]vumount\f[R] is just a wrapper to the \f[CB]mount\f[R](1) system
call (the command \f[CB]mount(8)\f[R] does much much more, it is setuid
root and requires real uid to be root to permit filesystem mounting
(\f[CB]mount\f[R](8) works in \f[CB]umvu\f[R] adding a module of uid/gid
virtualization).
.SS create a disk image, partition it, create a filesystem and mount it
In this example an 1GiB empty file is seen as a virtual disk, this disk
gets partitioned (GPT), an ext4 file system is created on its first
partition and finally this file system is mounted on /mnt
.PP
start the hypervisor, and run a bash \f[I]inside\f[R] the partial
virtual machine
.IP
.EX
$ umvu bash
.EE
.PP
This is the prompt of the partial virtualized shell, let us change it to
$$ to show the difference
.IP
.EX
$ PS1=\[aq]\[rs]$\[rs]$ \[aq]
.EE
.PP
let us load vudev and vufuse: vudev to virtualize devices and vufuse as
in the previous example
.IP
.EX
$$ vu_insmod vudev vufuse
.EE
.PP
create a 1 GiB large empty file
.IP
.EX
$$ truncate \-s 1G /tmp/disk
$$ ls \-l /tmp/disk
\-rw\-r\-\-r\-\- 1 renzo renzo 1073741824 Jun  3 11:55 /tmp/disk
.EE
.PP
let us mount the empty file as a partitioned virtual disk:
.IP
.EX
$$ vumount \-t vudevpartx /tmp/disk /dev/hda
Bad MBR signature 0 0
.EE
.PP
clearly if not a partitioned disk, yet.
Let us add a partitioning scheme:
.IP
.EX
$$  /sbin/gdisk /dev/hda
GPT fdisk (gdisk) version 1.0.3

Partition table scan:
MBR: not present
BSD: not present
APM: not present
GPT: not present

Creating new GPT entries.

Command (? for help):  n
Partition number (1\-128, default 1):
First sector (34\-2097118, default = 2048) or {+\-}size{KMGTP}:
Last sector (2048\-2097118, default = 2097118) or {+\-}size{KMGTP}: +200M
Current type is \[aq]Linux filesystem\[aq]
Hex code or GUID (L to show codes, Enter = 8300):
Changed type of partition to \[aq]Linux filesystem\[aq]

Command (? for help): n
Partition number (2\-128, default 2):
First sector (34\-2097118, default = 411648) or {+\-}size{KMGTP}:
Last sector (411648\-2097118, default = 2097118) or {+\-}size{KMGTP}:
Current type is \[aq]Linux filesystem\[aq]
Hex code or GUID (L to show codes, Enter = 8300):
Changed type of partition to \[aq]Linux filesystem\[aq]

Command (? for help): p
Disk /dev/hda: 2097152 sectors, 1024.0 MiB
Sector size (logical): 512 bytes
Disk identifier (GUID): F2A76123\-73ED\-4052\-BAFE\-6B37473E6187
Partition table holds up to 128 entries
Main partition table begins at sector 2 and ends at sector 33
First usable sector is 34, last usable sector is 2097118
Partitions will be aligned on 2048\-sector boundaries
Total free space is 2014 sectors (1007.0 KiB)

Number  Start (sector)    End (sector)  Size       Code  Name
1            2048          411647   200.0 MiB   8300  Linux filesystem
2          411648         2097118   823.0 MiB   8300  Linux filesystem

Command (? for help): w

Final checks complete. About to write GPT data. THIS WILL OVERWRITE EXISTING
PARTITIONS!!

Do you want to proceed? (Y/N): Y
OK; writing new GUID partition table (GPT) to /dev/hda.
The operation has completed successfully.
The disk has been partitioned:
$$  ls \-l /dev/hda1
brw\-\-\-\-\-\-\- 0 renzo renzo 0, 1 Jan  1  1970 /dev/hda1
$$ ls \-l /dev/hda2
brw\-\-\-\-\-\-\- 0 renzo renzo 0, 2 Jan  1  1970 /dev/hda2
.EE
.PP
Now it is possible to create an ext4 partition on /dev/hda1
.IP
.EX
$$ /sbin/mkfs.ext4 /dev/hda1
mke2fs 1.45.1 (12\-May\-2019)
warning: Unable to get device geometry for /dev/hda1
Creating filesystem with 204800 1k blocks and 51200 inodes
Filesystem UUID: c96c6499\-40cd\-43df\-addf\-52e06d7e6842
Superblock backups stored on blocks:
        8193, 24577, 40961, 57345, 73729

Allocating group tables: done
Writing inode tables: done
Creating journal (4096 blocks): done
  Writing superblocks and filesystem accounting information: done
.EE
.PP
now the file system on /dev/hda1 can be mounted on /mnt
.IP
.EX
$$ vumount \-t vufuseext2 \-o rw+ /dev/hda1 /mnt
.EE
.PP
add a significative file on /mnt
.IP
.EX
$$ echo ciao * /mnt/hello
$$ ls \-l /mnt
total 13
\-rw\-r\-\-r\-\- 1 renzo renzo     5 Jun  3 12:09 hello
drwx\-\-\-\-\-\- 2 root  root  12288 Jun  3 12:06 lost+found
$$ vuumount /mnt
$$ vuumount /dev/hda
$$ exit
$
.EE
.SS mount a user\-level networking stack
It is possible to provide network partial virtualization using the
\f[CB]vunet\f[R] module
.PP
start the hypervisor, and run a bash \f[I]inside\f[R] the partial
virtual machine
.IP
.EX
$ umvu bash
.EE
.PP
This is the prompt of the partial virtualized shell, let us change it to
$$ to show the difference
.IP
.EX
$ PS1=\[aq]\[rs]$\[rs]$ \[aq]
.EE
.PP
let us load vunet
.IP
.EX
$$ vu_insmod vunet
.EE
.PP
the following command #mounts# a vde network on /dev/net/myvde.
(see https://github.com/rd235/vdeplug4)
.IP
.EX
$$ vumount \-t vunetvdestack vxvde:// /dev/net/myvde
.EE
.PP
vustack is the command to select the stack to use.
.IP
.EX
$$ vustack /dev/net/myvde ip link
1: lo: *LOOPBACK* mtu 65536 qdisc noop state DOWN mode DEFAULT group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: vde0: *BROADCAST,MULTICAST* mtu 1500 qdisc noop state DOWN mode DEFAULT group default qlen 1000
    link/ether 7e:76:c0:d7:3b:37 brd ff:ff:ff:ff:ff:ff
.EE
.PP
without vustack I can still access the stack provided by the linux
kernel
.IP
.EX
$$ ip link
1: lo: *LOOPBACK,UP,LOWER_UP* mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: eth0: *BROADCAST,MULTICAST,UP,LOWER_UP* mtu 1500 qdisc pfifo_fast state UP mode DEFAULT group default qlen 1000
    link/ether 80:aa:bb:cc:dd:ee brd ff:ff:ff:ff:ff:ff
.EE
.PP
let us start a bash using /dev/net/myvde as itsdfault net
.IP
.EX
$$ vustack /dev/net/myvde bash
$ PS1=\[aq]\[rs]$N\[rs]$ \[aq]
.EE
.PP
let us configure the net
.IP
.EX
$N$ ip addr add 192.168.250.250/24 dev vde0
$N$ ip link set vde0 up
$N$ ip route add default via 192.168.250.1
$N$ ip addr
1: lo: *LOOPBACK* mtu 65536 qdisc noop state DOWN group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: vde0: *BROADCAST,MULTICAST,UP,LOWER_UP* mtu 1500 qdisc pfifo_fast state UNKNOWN group default qlen 1000
    link/ether 7e:76:c0:d7:3b:37 brd ff:ff:ff:ff:ff:ff
    inet 192.168.250.250/24 scope global vde0
       valid_lft forever preferred_lft forever
    inet6 fe80::7c76:c0ff:fed7:3b37/64 scope link
       valid_lft forever preferred_lft forever
$N$ ip route
default via 192.168.250.1 dev vde0
192.168.250.0/24 dev vde0 proto kernel scope link src 192.168.250.250
$N$ ping 80.80.80.80
PING 80.80.80.80 (80.80.80.80) 56(84) bytes of data.
64 bytes from 80.80.80.80: icmp_seq=1 ttl=52 time=56.9 ms
64 bytes from 80.80.80.80: icmp_seq=2 ttl=52 time=57.9 ms
\[ha]C
$N$
.EE
.SH SEE ALSO
vu_insmod(1), vu_lsmod(1), vu_rmmod(1), vumount(1), vuumount(1),
vudebug(1)
.SH AUTHOR
VirtualSquare.
Project leader: Renzo Davoli
